<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Assert Node.js v5.6.0 Manual &amp; Documentation</title>

  <link rel="stylesheet" href="assets/style.css">
  <link rel="stylesheet" href="assets/sh.css">
  <link rel="canonical" href="assert.html">
</head>
<body class="alt apidoc" id="api-section-assert">
  <div id="content" class="clearfix">
    <div id="column2" class="interior">
      <div class="no-scrollbar">
        <div id="intro" class="interior">
          <a href="./" title="Go back to the home page">
            Node.js (1)
          </a>
        </div>
        <ul>
<li><a class="nav-documentation" href="documentation.html">About these Docs</a></li>
<li><a class="nav-synopsis" href="synopsis.html">Synopsis</a></li>
<li><a class="nav-assert active" href="assert.html">Assertion Testing</a></li>
<li><a class="nav-buffer" href="buffer.html">Buffer</a></li>
<li><a class="nav-addons" href="addons.html">C/C++ Addons</a></li>
<li><a class="nav-child_process" href="child_process.html">Child Processes</a></li>
<li><a class="nav-cluster" href="cluster.html">Cluster</a></li>
<li><a class="nav-console" href="console.html">Console</a></li>
<li><a class="nav-crypto" href="crypto.html">Crypto</a></li>
<li><a class="nav-debugger" href="debugger.html">Debugger</a></li>
<li><a class="nav-dns" href="dns.html">DNS</a></li>
<li><a class="nav-domain" href="domain.html">Domain</a></li>
<li><a class="nav-errors" href="errors.html">Errors</a></li>
<li><a class="nav-events" href="events.html">Events</a></li>
<li><a class="nav-fs" href="fs.html">File System</a></li>
<li><a class="nav-globals" href="globals.html">Globals</a></li>
<li><a class="nav-http" href="http.html">HTTP</a></li>
<li><a class="nav-https" href="https.html">HTTPS</a></li>
<li><a class="nav-modules" href="modules.html">Modules</a></li>
<li><a class="nav-net" href="net.html">Net</a></li>
<li><a class="nav-os" href="os.html">OS</a></li>
<li><a class="nav-path" href="path.html">Path</a></li>
<li><a class="nav-process" href="process.html">Process</a></li>
<li><a class="nav-punycode" href="punycode.html">Punycode</a></li>
<li><a class="nav-querystring" href="querystring.html">Query Strings</a></li>
<li><a class="nav-readline" href="readline.html">Readline</a></li>
<li><a class="nav-repl" href="repl.html">REPL</a></li>
<li><a class="nav-stream" href="stream.html">Stream</a></li>
<li><a class="nav-string_decoder" href="string_decoder.html">String Decoder</a></li>
<li><a class="nav-timers" href="timers.html">Timers</a></li>
<li><a class="nav-tls" href="tls.html">TLS/SSL</a></li>
<li><a class="nav-tty" href="tty.html">TTY</a></li>
<li><a class="nav-dgram" href="dgram.html">UDP/Datagram</a></li>
<li><a class="nav-url" href="url.html">URL</a></li>
<li><a class="nav-util" href="util.html">Utilities</a></li>
<li><a class="nav-v8" href="v8.html">V8</a></li>
<li><a class="nav-vm" href="vm.html">VM</a></li>
<li><a class="nav-zlib" href="zlib.html">ZLIB</a></li>
</ul>

      </div>
    </div>

    <div id="column1" data-id="assert" class="interior">
      <header>
        <h1>Node.js v5.6.0 Documentation</h1>
        <div id="gtoc">
          <p>
            <a href="index.html" name="toc">Index</a> |
            <a href="all.html">View on single page</a> |
            <a href="assert.json">View as JSON</a>
          </p>
        </div>
        <hr>
      </header>

      <div id="toc">
        <h2>Table of Contents</h2>
        <ul>
<li><a href="assert.html#assert_assert">Assert</a><ul>
<li><a href="assert.html#assert_assert_value_message">assert(value[, message])</a></li>
<li><a href="assert.html#assert_assert_deepequal_actual_expected_message">assert.deepEqual(actual, expected[, message])</a></li>
<li><a href="assert.html#assert_assert_deepstrictequal_actual_expected_message">assert.deepStrictEqual(actual, expected[, message])</a></li>
<li><a href="assert.html#assert_assert_doesnotthrow_block_error_message">assert.doesNotThrow(block[, error][, message])</a></li>
<li><a href="assert.html#assert_assert_equal_actual_expected_message">assert.equal(actual, expected[, message])</a></li>
<li><a href="assert.html#assert_assert_fail_actual_expected_message_operator">assert.fail(actual, expected, message, operator)</a></li>
<li><a href="assert.html#assert_assert_iferror_value">assert.ifError(value)</a></li>
<li><a href="assert.html#assert_assert_notdeepequal_actual_expected_message">assert.notDeepEqual(actual, expected[, message])</a></li>
<li><a href="assert.html#assert_assert_notdeepstrictequal_actual_expected_message">assert.notDeepStrictEqual(actual, expected[, message])</a></li>
<li><a href="assert.html#assert_assert_notequal_actual_expected_message">assert.notEqual(actual, expected[, message])</a></li>
<li><a href="assert.html#assert_assert_notstrictequal_actual_expected_message">assert.notStrictEqual(actual, expected[, message])</a></li>
<li><a href="assert.html#assert_assert_ok_value_message">assert.ok(value[, message])</a></li>
<li><a href="assert.html#assert_assert_strictequal_actual_expected_message">assert.strictEqual(actual, expected[, message])</a></li>
<li><a href="assert.html#assert_assert_throws_block_error_message">assert.throws(block[, error][, message])</a></li>
</ul>
</li>
</ul>

      </div>

      <div id="apicontent">
        <h1>Assert<span><a class="mark" href="assert.html#assert_assert" id="assert_assert">#</a></span></h1>
<pre class="api_stability_3">Stability: 3 - Locked</pre><p>The <code>assert</code> module provides a simple set of assertion tests that can be used to
test invariants. The module is intended for internal use by Node.js, but can be
used in application code via <code>require(&#39;assert&#39;)</code>. However, <code>assert</code> is not a
testing framework, and is not intended to be used as a general purpose assertion
library.

</p>
<p>The API for the <code>assert</code> module is <a href="documentation.html#documentation_stability_index">Locked</a>. This means that there will be no
additions or changes to any of the methods implemented and exposed by
the module.

</p>
<h2>assert(value[, message])<span><a class="mark" href="assert.html#assert_assert_value_message" id="assert_assert_value_message">#</a></span></h2>
<p>An alias of <a href="assert.html#assert_assert_ok_value_message"><code>assert.ok()</code></a> .

</p>
<pre><code class="js">const assert = require(&#39;assert&#39;);

assert(true);  // OK
assert(1);     // OK
assert(false);
  // throws &quot;AssertionError: false == true&quot;
assert(0);
  // throws &quot;AssertionError: 0 == true&quot;
assert(false, &#39;it\&#39;s false&#39;);
  // throws &quot;AssertionError: it&#39;s false&quot;</code></pre>
<h2>assert.deepEqual(actual, expected[, message])<span><a class="mark" href="assert.html#assert_assert_deepequal_actual_expected_message" id="assert_assert_deepequal_actual_expected_message">#</a></span></h2>
<p>Tests for deep equality between the <code>actual</code> and <code>expected</code> parameters.
Primitive values are compared with the equal comparison operator ( <code>==</code> ).

</p>
<p>Only enumerable &quot;own&quot; properties are considered. The <code>deepEqual()</code>
implementation does not test object prototypes, attached symbols, or
non-enumerable properties. This can lead to some potentially surprising
results. For example, the following example does not throw an <code>AssertionError</code>
because the properties on the <a href="errors.html#errors_class_error"><code>Error</code></a> object are non-enumerable:

</p>
<pre><code class="js">// WARNING: This does not throw an AssertionError!
assert.deepEqual(Error(&#39;a&#39;), Error(&#39;b&#39;));</code></pre>
<p>&quot;Deep&quot; equality means that the enumerable &quot;own&quot; properties of child objects
are evaluated also:

</p>
<pre><code class="js">const assert = require(&#39;assert&#39;);

const obj1 = {
  a : {
    b : 1
  }
};
const obj2 = {
  a : {
    b : 2
  }
};
const obj3 = {
  a : {
    b : 1
  }
}
const obj4 = Object.create(obj1);

assert.deepEqual(obj1, obj1);
  // OK, object is equal to itself

assert.deepEqual(obj1, obj2);
  // AssertionError: { a: { b: 1 } } deepEqual { a: { b: 2 } }
  // values of b are different

assert.deepEqual(obj1, obj3);
  // OK, objects are equal

assert.deepEqual(obj1, obj4);
  // AssertionError: { a: { b: 1 } } deepEqual {}
  // Prototypes are ignored</code></pre>
<p>If the values are not equal, an <code>AssertionError</code> is thrown with a <code>message</code>
property set equal to the value of the <code>message</code> parameter. If the <code>message</code>
parameter is undefined, a default error message is assigned.

</p>
<h2>assert.deepStrictEqual(actual, expected[, message])<span><a class="mark" href="assert.html#assert_assert_deepstrictequal_actual_expected_message" id="assert_assert_deepstrictequal_actual_expected_message">#</a></span></h2>
<p>Generally identical to <a href="assert.html#assert_assert_deepequal_actual_expected_message"><code>assert.deepEqual()</code></a> with the exception that primitive
values are compared using the strict equality operator ( <code>===</code> ).

</p>
<pre><code class="js">const assert = require(&#39;assert&#39;);

assert.deepEqual({a:1}, {a:&#39;1&#39;});
  // OK, because 1 == &#39;1&#39;

assert.deepStrictEqual({a:1}, {a:&#39;1&#39;});
  // AssertionError: { a: 1 } deepStrictEqual { a: &#39;1&#39; }
  // because 1 !== &#39;1&#39; using strict equality</code></pre>
<p>If the values are not equal, an <code>AssertionError</code> is thrown with a <code>message</code>
property set equal to the value of the <code>message</code> parameter. If the <code>message</code>
parameter is undefined, a default error message is assigned.

</p>
<h2>assert.doesNotThrow(block[, error][, message])<span><a class="mark" href="assert.html#assert_assert_doesnotthrow_block_error_message" id="assert_assert_doesnotthrow_block_error_message">#</a></span></h2>
<p>Asserts that the function <code>block</code> does not throw an error. See
<a href="assert.html#assert_assert_throws_block_error_message"><code>assert.throws()</code></a> for more details.

</p>
<p>When <code>assert.doesNotThrow()</code> is called, it will immediately call the <code>block</code>
function.

</p>
<p>If an error is thrown and it is the same type as that specified by the <code>error</code>
parameter, then an <code>AssertionError</code> is thrown. If the error is of a different
type, or if the <code>error</code> parameter is undefined, the error is propagated back
to the caller.

</p>
<p>The following, for instance, will throw the <a href="errors.html#errors_class_typeerror"><code>TypeError</code></a> because there is no
matching error type in the assertion:

</p>
<pre><code class="js">assert.doesNotThrow(
  () =&gt; {
    throw new TypeError(&#39;Wrong value&#39;);
  },
  SyntaxError
);</code></pre>
<p>However, the following will result in an <code>AssertionError</code> with the message
&#39;Got unwanted exception (TypeError)..&#39;:

</p>
<pre><code class="js">assert.doesNotThrow(
  () =&gt; {
    throw new TypeError(&#39;Wrong value&#39;);
  },
  TypeError
);</code></pre>
<p>If an <code>AssertionError</code> is thrown and a value is provided for the <code>message</code>
parameter, the value of <code>message</code> will be appended to the <code>AssertionError</code>
message:

</p>
<pre><code class="js">assert.doesNotThrow(
  () =&gt; {
    throw new TypeError(&#39;Wrong value&#39;);
  },
  TypeError,
  &#39;Whoops&#39;
);
// Throws: AssertionError: Got unwanted exception (TypeError). Whoops</code></pre>
<h2>assert.equal(actual, expected[, message])<span><a class="mark" href="assert.html#assert_assert_equal_actual_expected_message" id="assert_assert_equal_actual_expected_message">#</a></span></h2>
<p>Tests shallow, coercive equality between the <code>actual</code> and <code>expected</code> parameters
using the equal comparison operator ( <code>==</code> ).

</p>
<pre><code class="js">const assert = require(&#39;assert&#39;);

assert.equal(1, 1);
  // OK, 1 == 1
assert.equal(1, &#39;1&#39;);
  // OK, 1 == &#39;1&#39;

assert.equal(1, 2);
  // AssertionError: 1 == 2
assert.equal({a: {b: 1}}, {a: {b: 1}});
  //AssertionError: { a: { b: 1 } } == { a: { b: 1 } }</code></pre>
<p>If the values are not equal, an <code>AssertionError</code> is thrown with a <code>message</code>
property set equal to the value of the <code>message</code> parameter. If the <code>message</code>
parameter is undefined, a default error message is assigned.

</p>
<h2>assert.fail(actual, expected, message, operator)<span><a class="mark" href="assert.html#assert_assert_fail_actual_expected_message_operator" id="assert_assert_fail_actual_expected_message_operator">#</a></span></h2>
<p>Throws an <code>AssertionError</code>. If <code>message</code> is falsy, the error message is set as
the values of <code>actual</code> and <code>expected</code> separated by the provided <code>operator</code>.
Otherwise, the error message is the value of <code>message</code>.

</p>
<pre><code class="js">const assert = require(&#39;assert&#39;);

assert.fail(1, 2, undefined, &#39;&gt;&#39;);
  // AssertionError: 1 &gt; 2

assert.fail(1, 2, &#39;whoops&#39;, &#39;&gt;&#39;);
  // AssertionError: whoops</code></pre>
<h2>assert.ifError(value)<span><a class="mark" href="assert.html#assert_assert_iferror_value" id="assert_assert_iferror_value">#</a></span></h2>
<p>Throws <code>value</code> if <code>value</code> is truthy. This is useful when testing the <code>error</code>
argument in callbacks.

</p>
<pre><code class="js">const assert = require(&#39;assert&#39;);

assert.ifError(0); // OK
assert.ifError(1); // Throws 1
assert.ifError(&#39;error&#39;) // Throws &#39;error&#39;
assert.ifError(new Error()); // Throws Error</code></pre>
<h2>assert.notDeepEqual(actual, expected[, message])<span><a class="mark" href="assert.html#assert_assert_notdeepequal_actual_expected_message" id="assert_assert_notdeepequal_actual_expected_message">#</a></span></h2>
<p>Tests for any deep inequality. Opposite of <a href="assert.html#assert_assert_deepequal_actual_expected_message"><code>assert.deepEqual()</code></a>.

</p>
<pre><code class="js">const assert = require(&#39;assert&#39;);

const obj1 = {
  a : {
    b : 1
  }
};
const obj2 = {
  a : {
    b : 2
  }
};
const obj3 = {
  a : {
    b : 1
  }
}
const obj4 = Object.create(obj1);

assert.notDeepEqual(obj1, obj1);
  // AssertionError: { a: { b: 1 } } notDeepEqual { a: { b: 1 } }

assert.notDeepEqual(obj1, obj2);
  // OK, obj1 and obj2 are not deeply equal

assert.notDeepEqual(obj1, obj3);
  // AssertionError: { a: { b: 1 } } notDeepEqual { a: { b: 1 } }

assert.notDeepEqual(obj1, obj4);
  // OK, obj1 and obj2 are not deeply equal</code></pre>
<p>If the values are deeply equal, an <code>AssertionError</code> is thrown with a <code>message</code>
property set equal to the value of the <code>message</code> parameter. If the <code>message</code>
parameter is undefined, a default error message is assigned.

</p>
<h2>assert.notDeepStrictEqual(actual, expected[, message])<span><a class="mark" href="assert.html#assert_assert_notdeepstrictequal_actual_expected_message" id="assert_assert_notdeepstrictequal_actual_expected_message">#</a></span></h2>
<p>Tests for deep strict inequality. Opposite of <a href="assert.html#assert_assert_deepstrictequal_actual_expected_message"><code>assert.deepStrictEqual()</code></a>.

</p>
<pre><code class="js">const assert = require(&#39;assert&#39;);

assert.notDeepEqual({a:1}, {a:&#39;1&#39;});
  // AssertionError: { a: 1 } notDeepEqual { a: &#39;1&#39; }

assert.notDeepStrictEqual({a:1}, {a:&#39;1&#39;});
  // OK</code></pre>
<p>If the values are deeply and strictly equal, an <code>AssertionError</code> is thrown
with a <code>message</code> property set equal to the value of the <code>message</code> parameter. If
the <code>message</code> parameter is undefined, a default error message is assigned.

</p>
<h2>assert.notEqual(actual, expected[, message])<span><a class="mark" href="assert.html#assert_assert_notequal_actual_expected_message" id="assert_assert_notequal_actual_expected_message">#</a></span></h2>
<p>Tests shallow, coercive inequality with the not equal comparison operator
( <code>!=</code> ).

</p>
<pre><code class="js">const assert = require(&#39;assert&#39;);

assert.notEqual(1, 2);
  // OK

assert.notEqual(1, 1);
  // AssertionError: 1 != 1

assert.notEqual(1, &#39;1&#39;);
  // AssertionError: 1 != &#39;1&#39;</code></pre>
<p>If the values are equal, an <code>AssertionError</code> is thrown with a <code>message</code>
property set equal to the value of the <code>message</code> parameter. If the <code>message</code>
parameter is undefined, a default error message is assigned.

</p>
<h2>assert.notStrictEqual(actual, expected[, message])<span><a class="mark" href="assert.html#assert_assert_notstrictequal_actual_expected_message" id="assert_assert_notstrictequal_actual_expected_message">#</a></span></h2>
<p>Tests strict inequality as determined by the strict not equal operator
( <code>!==</code> ).

</p>
<pre><code class="js">const assert = require(&#39;assert&#39;);

assert.notStrictEqual(1, 2);
  // OK

assert.notStrictEqual(1, 1);
  // AssertionError: 1 != 1

assert.notStrictEqual(1, &#39;1&#39;);
  // OK</code></pre>
<p>If the values are strictly equal, an <code>AssertionError</code> is thrown with a
<code>message</code> property set equal to the value of the <code>message</code> parameter. If the
<code>message</code> parameter is undefined, a default error message is assigned.

</p>
<h2>assert.ok(value[, message])<span><a class="mark" href="assert.html#assert_assert_ok_value_message" id="assert_assert_ok_value_message">#</a></span></h2>
<p>Tests if <code>value</code> is truthy. It is equivalent to
<code>assert.equal(!!value, true, message)</code>.

</p>
<p>If <code>value</code> is not truthy, an <code>AssertionError</code> is thrown with a <code>message</code>
property set equal to the value of the <code>message</code> parameter. If the <code>message</code>
parameter is <code>undefined</code>, a default error message is assigned.

</p>
<pre><code class="js">const assert = require(&#39;assert&#39;);

assert.ok(true);  // OK
assert.ok(1);     // OK
assert.ok(false);
  // throws &quot;AssertionError: false == true&quot;
assert.ok(0);
  // throws &quot;AssertionError: 0 == true&quot;
assert.ok(false, &#39;it\&#39;s false&#39;);
  // throws &quot;AssertionError: it&#39;s false&quot;</code></pre>
<h2>assert.strictEqual(actual, expected[, message])<span><a class="mark" href="assert.html#assert_assert_strictequal_actual_expected_message" id="assert_assert_strictequal_actual_expected_message">#</a></span></h2>
<p>Tests strict equality as determined by the strict equality operator ( <code>===</code> ).

</p>
<pre><code class="js">const assert = require(&#39;assert&#39;);

assert.strictEqual(1, 2);
  // AssertionError: 1 === 2

assert.strictEqual(1, 1);
  // OK

assert.strictEqual(1, &#39;1&#39;);
  // AssertionError: 1 === &#39;1&#39;</code></pre>
<p>If the values are not strictly equal, an <code>AssertionError</code> is thrown with a
<code>message</code> property set equal to the value of the <code>message</code> parameter. If the
<code>message</code> parameter is undefined, a default error message is assigned.

</p>
<h2>assert.throws(block[, error][, message])<span><a class="mark" href="assert.html#assert_assert_throws_block_error_message" id="assert_assert_throws_block_error_message">#</a></span></h2>
<p>Expects the function <code>block</code> to throw an error. If specified, <code>error</code> can be a
constructor, <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions"><code>RegExp</code></a>, or validation function.

</p>
<p>Validate instanceof using constructor:

</p>
<pre><code class="js">assert.throws(
  () =&gt; {
    throw new Error(&#39;Wrong value&#39;);
  },
  Error
);</code></pre>
<p>Validate error message using <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions"><code>RegExp</code></a>:

</p>
<pre><code class="js">assert.throws(
  () =&gt; {
    throw new Error(&#39;Wrong value&#39;);
  },
  /value/
);</code></pre>
<p>Custom error validation:

</p>
<pre><code class="js">assert.throws(
  () =&gt; {
    throw new Error(&#39;Wrong value&#39;);
  },
  function(err) {
    if ( (err instanceof Error) &amp;&amp; /value/.test(err) ) {
      return true;
    }
  },
  &#39;unexpected error&#39;
);</code></pre>

      </div>
    </div>
  </div>
  <script src="assets/sh_main.js"></script>
  <script src="assets/sh_javascript.min.js"></script>
  <script>highlight(undefined, undefined, 'pre');</script>
</body>
</html>

